Detailed Technical Analysis

Root Cause Investigation

When running interactive terminal applications (like Claude Code) inside srt, users encounter:

Error: setRawMode EPERM
    at ReadStream.setRawMode (node:tty:81:24)

This occurs because:

1. Node.js readline module calls setRawMode() on stdin to enable character-by-character input
2. setRawMode() requires ioctl operations on the controlling terminal device (/dev/ttys*)
3. macOS Seatbelt sandbox blocks ioctl operations on PTY devices by default

Code Path Analysis

The sandbox profile generation in macos-sandbox-utils.ts already supports PTY access:

// Lines 585-598
if (allowPty) {
  profile.push('(allow pseudo-tty)')  // Master PTY permission
  profile.push('(allow file-ioctl')
  profile.push('  (literal "/dev/ptmx")')
  profile.push('  (regex #"^/dev/ttys")')  // Slave TTYs
  profile.push(')')
  profile.push('(allow file-read* file-write*')
  profile.push('  (literal "/dev/ptmx")')
  profile.push('  (regex #"^/dev/ttys")')
  profile.push(')')
}

The allowPty option exists in the config schema (sandbox-config.ts:174-177) and is properly propagated through SandboxManager.wrapWithSandbox() at line 536:

const allowPty = customConfig?.allowPty ?? config?.allowPty

However, there was no CLI flag to enable this option for one-off interactive commands.

Why This Matters

1. Security tools should be usable - If users can't run interactive applications, they'll either:

   • Skip sandboxing entirely (worse security)
   • Use workarounds that may introduce vulnerabilities

2. Explicit opt-in is correct - The --tty flag maintains the secure-by-default philosophy while enabling legitimate use cases

3. The code existed, just wasn't exposed - This PR is minimal because the underlying functionality was already implemented and tested

Security Considerations

PTY access does NOT bypass the core sandbox restrictions:

PTY access does allow:

• Terminal escape sequence injection (limited impact - user is at terminal)
• Keystroke simulation (only affects the sandboxed process's terminal)
• Raw mode for character-by-character input

Alternative Solutions Considered

The CLI flag approach was chosen because:

• Explicit is better than implicit for security tools
• Per-command control is more flexible than global config
• Users can combine with config file for persistent setting

Testing Notes

• The --tty flag shows correctly in --help
• Debug mode confirms allowPty: true is set when flag is used
• Pre-commit hooks (eslint, prettier) pass
• Build succeeds

For full interactive testing, users should test with actual TUI applications like vim or htop on their macOS system.

PS: I love you guys <3 My public GH before Claude Code was almost empty of little green squares. Kudos on the best app of the year.

we are running into an issue using the https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk where when sandbox mode is enabled (on mac and windows users) the agent just seems to freeze up. We had to turn off sandbox mode because of it. Hopefully this PR fixes that issue and it can get merge upstream to the claude-agent-sdk

Would love to see this get merged!